.. _security_auth_providers:

Authentication providers
========================

The following authentication providers are available in GeoServer:
 
* Authentication of a username/password against a :ref:`user/group service <security_rolesystem_usergroupservices>`
* Authentication against an LDAP server
* Authentication by connecting to a database through JDBC


.. _security_auth_provider_userpasswd:

Username/password authentication
--------------------------------

Username and password authentication is the default authentication provider. It uses a :ref:`user/group service <security_rolesystem_usergroupservices>` to authenticate.

The provider simply takes the username/password from an incoming request (such as a Basic Authentication request), then loads the user information from the user/group service and verifies the credentials.

.. _security_auth_provider_ldap:

LDAP authentication
-------------------

The LDAP authentication provider allows for authentication against a `Lightweight Directory Access Protocol <http://en.wikipedia.org/wiki/Lightweight_Directory_Access_Protocol>`_ (LDAP) server. The provider takes the username/password from the incoming request and attempts to connect to the LDAP server with those credentials. 

.. note:: Currently only LDAP Bind authentication is supported.

Role assignment
~~~~~~~~~~~~~~~

The LDAP provider offers two options for role assignment for authenticated users:

* Convert the user's LDAP groups into roles
* Employ a user/group service

The following LDAP database will illustrate the first option::

    dn: ou=people,dc=acme,dc=com
    objectclass: organizationalUnit
    ou: people
    
    dn: uid=bob,ou=people,dc=acme,dc=com
    objectclass: person
    uid: bob
    
    dn: ou=groups,dc=acme,dc=com
    objectclass: organizationalUnit
    ou: groups
    
    dn: cn=workers,ou=groups,dc=acme,dc=com
    objectclass: groupOfNames
    cn: users
    member: uid=bob,ou=people,dc=acme,dc=com

The above scenario defines a user with the ``uid`` of ``bob``, and a ``group`` named ``workers`` of which ``bob`` is a member. After authentication, ``bob`` will be assigned the role ``ROLE_WORKERS``. The role name is generated by concatenating ``ROLE_`` with the name of the group in upper case.

.. note:: When the LDAP server doesn't allow searching in an anonymous context, the bindBeforeGroupSearch option should be enabled to avoid errors.

In the case of using a :ref:`user/group service <security_rolesystem_usergroupservices>`, the user/group service is queried for the user following authentication, and the role assignment is performed by both the user/group service and the active :ref:`role service <security_rolesystem_roleservices>`. When using this option, any password defined for the user in the user/group service database is ignored.

.. _security_auth_provider_ldap_secure:

Secure LDAP connections
~~~~~~~~~~~~~~~~~~~~~~~

There are two ways to create a secure LDAP connection with the server. The first is to directly specify a secure connection by using the **ldaps** protocol as part of the *Server URL*. This typically requires changing the connection port to **port 636** rather than 389.

The second method involves using **STARTTLS** (Transport Layer Security) to negotiate a secure connection over a non-secure one. The negotiation takes place over the non-secure URL using the "ldap" protocol on port 389. To use this option, the *Use TLS* flag must be set.

.. warning::  Using TLS for connections will prevent GeoServer from being able to pool LDAP connections. This means a new LDAP connection will be created and destroyed for each authentication, resulting in loss of performance.


.. _security_auth_provider_jdbc:

JDBC authentication
-------------------

The JDBC authentication provider authenticates by connecting to a database over `JDBC <http://en.wikipedia.org/wiki/Java_Database_Connectivity>`_.

The provider takes the username/password from the incoming request and attempts to create a database connection using those credentials. Optionally the provider may use a :ref:`user/group service <security_rolesystem_usergroupservices>` to load user information after a successful authentication. In this context the user/group service will not be used for password verification, only for role assignment.

.. note:: To use the user/group service for password verification, please see the section on :ref:`security_auth_provider_userpasswd`.

